// Copyright (c) Appeon. All rights reserved.
// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. 
// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.

using System;

namespace SnapObjects.Data
{
    /// <summary>
    ///     Represents an object which can be used to build SQL.
    /// </summary>
    public interface ISqlBuilder : ISqlBuilderBase, ICloneable<ISqlBuilder>
    {
        /// <summary>
        ///     Gets a read-only ISqlReadOnlyBuilder object generated by the clone of the current object.
        /// </summary>
        /// <returns>
        ///     A read-only ISqlReadOnlyBuilder object which can generate the same SQL statements as the current object.
        /// </returns>
        ISqlReadOnlyBuilder ToReadOnly();

        /// <summary>
        ///     Adds the parameters which will be used in the SQL statement to the current object.
        /// </summary>
        /// <param name="parameters">
        ///     One or more SQL parameters to be used in the SQL statement. You can use the SqlBuilder.Parameter 
        ///     method to create a SQL parameter.
        /// </param>
        /// <returns>
        ///     Returns false if the parameter name is not specified or the parameter name already exists; otherwise, returns true.
        /// </returns>
        bool AddParameters(params ISqlParameter[] parameters);

        /// <summary>
        ///     Gets the placeholder string for a SQL parameter.
        /// </summary>
        /// <param name="name">The name of the SQL parameter to get the placeholder string.</param>
        /// <returns>
        ///     Returns the placeholder string for the SQL parameter if the parameter name exists in the current object.
        /// </returns>
        string GetParameterPlacehold(string name);

        /// <summary>
        ///     Clears the SQL statement and all of the SQL parameters defined in the current object.
        /// </summary>
        /// <returns>Returns the current object.</returns>
        ISqlBuilder Reset();
    }
}
